HAL I3C types migration

This section provides information about the HAL I3C types migration.

HAL I3C state type definition

HAL1

HAL2 

typedef enum
{
  HAL_I3C_STATE_RESET,
  HAL_I3C_STATE_READY,
  HAL_I3C_STATE_BUSY,
  HAL_I3C_STATE_BUSY_TX,
  HAL_I3C_STATE_BUSY_RX,
  HAL_I3C_STATE_BUSY_TX_RX,
  HAL_I3C_STATE_BUSY_DAA,
  HAL_I3C_STATE_LISTEN,
  HAL_I3C_STATE_ABORT,
  HAL_I3C_STATE_ERROR
} HAL_I3C_StateTypeDef;

typedef enum
{
  HAL_I3C_STATE_RESET,
  HAL_I3C_STATE_INIT,
  HAL_I3C_STATE_IDLE,
  HAL_I3C_STATE_TX,
  HAL_I3C_STATE_RX,
  HAL_I3C_STATE_TX_RX,
  HAL_I3C_STATE_DAA,
  HAL_I3C_STATE_TGT_REQ,
  HAL_I3C_STATE_ABORT
} hal_i3c_state_t;

Related concept: Revised and optimized HAL state machine

HAL I3C callbacks ID type definition

HAL1

HAL2 

typedef enum
{
  HAL_I3C_CTRL_TX_COMPLETE_CB_ID,
  HAL_I3C_CTRL_RX_COMPLETE_CB_ID,
  HAL_I3C_CTRL_MULTIPLE_XFER_COMPLETE_CB_ID,
  HAL_I3C_CTRL_DAA_COMPLETE_CB_ID,
  HAL_I3C_TGT_REQ_DYNAMIC_ADDR_CB_ID,
  HAL_I3C_TGT_TX_COMPLETE_CB_ID,
  HAL_I3C_TGT_RX_COMPLETE_CB_ID,
  HAL_I3C_TGT_HOTJOIN_CB_ID,
  HAL_I3C_NOTIFY_CB_ID,
  HAL_I3C_ERROR_CB_ID,
  HAL_I3C_ABORT_CB_ID,
  HAL_I3C_MSPINIT_CB_ID,
  HAL_I3C_MSPDEINIT_CB_ID
} HAL_I3C_CallbackIDTypeDef;

Removed.

Note

The callback registration in HAL2 is handled by specific functions for each I3C event. See HAL I3C callbacks register and unregister functions for more details.

HAL_I3C_MSPINIT_CB_ID and HAL_I3C_MSPDEINIT_CB_ID are removed because the functions HAL_I3C_MspInit() and HAL_I3C_MspDeInit() are removed.

Related concepts:

HAL I3C operating modes type definition

HAL1

HAL2 

typedef enum
{
  HAL_I3C_MODE_NONE,
  HAL_I3C_MODE_CONTROLLER,
  HAL_I3C_MODE_TARGET
} HAL_I3C_ModeTypeDef;

typedef enum
{
  HAL_I3C_MODE_NONE,
  HAL_I3C_MODE_CTRL,
  HAL_I3C_MODE_TGT
} hal_i3c_mode_t;

HAL I3C bus characteristics register type definition

HAL1

HAL2 

typedef struct
{
  FunctionalState         MaxDataSpeedLimitation;
  FunctionalState         IBIRequestCapable;
  FunctionalState         IBIPayload;
  FunctionalState         OfflineCapable;
  FunctionalState         VirtualTargetSupport;
  FunctionalState         AdvancedCapabilities;
  FunctionalState         DeviceRole;
} I3C_BCRTypeDef;

typedef struct
{
  hal_i3c_max_speed_limitation_status_t   max_data_speed_limitation;
  hal_i3c_ibi_req_status_t                ibi_request_capable;
  hal_i3c_ibi_payload_status_t            ibi_payload;
  hal_i3c_offline_capable_status_t        offline_capable;
  hal_i3c_virtual_tgt_status_t            virtual_target_support;
  hal_i3c_adv_capabilities_status_t       advanced_capabilities;
  hal_i3c_ctrl_role_status_t              ctrl_role;
} hal_i3c_bcr_t;

HAL I3C CCC info type definition

HAL1

HAL2 

typedef struct
{
  uint32_t DynamicAddrValid;

  uint32_t DynamicAddr;
  uint32_t MaxWriteLength;
  uint32_t MaxReadLength;
  uint32_t ResetAction;
  uint32_t ActivityState;
  uint32_t HotJoinAllowed;

  uint32_t InBandAllowed;

  uint32_t CtrlRoleAllowed;

  uint32_t IBICRTgtAddr;
  uint32_t IBITgtNbPayload;
  uint32_t IBITgtPayload;
} I3C_CCCInfoTypeDef;

typedef struct
{
  uint32_t dynamic_addr_valid;

  uint32_t dynamic_addr;
  uint32_t max_write_data_size_byte;
  uint32_t max_read_data_size_byte;
  hal_i3c_reset_action_t reset_action;
  hal_i3c_activity_state_t activity_state;
  uint32_t hot_join_allowed;

  uint32_t in_band_allowed;

  uint32_t ctrl_role_allowed;

  uint32_t ibi_cr_tgt_addr;
  uint32_t ibi_tgt_nb_payload;
  uint32_t ibi_tgt_payload;
} hal_i3c_ccc_info_t;

HAL I3C CCC type definition

HAL1

HAL2 

typedef struct
{
  uint8_t            TargetAddr;
  uint8_t            CCC;
  I3C_DataTypeDef    CCCBuf;
  uint32_t           Direction;
} I3C_CCCTypeDef;

typedef struct
{
  uint8_t            TargetAddr;
  I3C_DataTypeDef    TxBuf;
  I3C_DataTypeDef    RxBuf;
  uint32_t           Direction;
} I3C_PrivateTypeDef;

typedef struct
{
  uint8_t  tgt_addr;
  uint8_t  ccc;
  uint32_t data_size_byte;
  hal_i3c_direction_t direction;
} hal_i3c_ccc_desc_t;

typedef struct
{
  uint8_t              tgt_addr;
  uint32_t             data_size_byte;
  hal_i3c_direction_t  direction;
} hal_i3c_private_desc_t;

HAL I3C control type definition

HAL1

HAL2 

typedef struct
{
  uint32_t *pBuffer;
  uint32_t  Size;
} I3C_ControlTypeDef;

typedef struct
{
  I3C_ControlTypeDef CtrlBuf;
  I3C_ControlTypeDef StatusBuf;
  I3C_DataTypeDef    TxBuf;
  I3C_DataTypeDef    RxBuf;
} I3C_XferTypeDef;

typedef struct
{
  uint32_t *p_tc_data;
  uint32_t tc_size_word;
  const uint8_t *p_tx_data;
  uint32_t tx_size_byte;
  uint8_t *p_rx_data;
  uint32_t rx_size_byte;
  hal_i3c_transfer_mode_t transfer_mode;
  uint32_t nb_tx_frame;
} hal_i3c_transfer_ctx_t;

HAL I3C control configuration type definition

The structure I3C_CtrlConfTypeDef and its associated function HAL_I3C_Ctrl_Config have been replaced by the following unitary functions.

HAL1

HAL2 

typedef struct
{
  uint8_t DynamicAddr;

  uint8_t StallTime;


  FunctionalState ACKStallState;

  FunctionalState CCCStallState;

  FunctionalState TxStallState;

  FunctionalState RxStallState;

  FunctionalState HotJoinAllowed;

  FunctionalState HighKeeperSDA;

} I3C_CtrlConfTypeDef;



hal_status_t HAL_I3C_CTRL_SetConfigOwnDynamicAddress(hal_i3c_handle_t *hi3c, uint32_t dynamic_address);

hal_status_t HAL_I3C_CTRL_SetConfigStallTime(const hal_i3c_handle_t *hi3c, uint32_t stall_time_cycle,
                                    uint32_t stall_features);

HAL_I3C_CTRL_SetConfigStallTime(&hi3c1, 0x10, HAL_I3C_CTRL_STALL_ACK);

HAL_I3C_CTRL_SetConfigStallTime(&hi3c1, 0x10, HAL_I3C_CTRL_STALL_CCC);

HAL_I3C_CTRL_SetConfigStallTime(&hi3c1, 0x10, HAL_I3C_CTRL_STALL_TX);

HAL_I3C_CTRL_SetConfigStallTime(&hi3c1, 0x10, HAL_I3C_CTRL_STALL_RX);

hal_status_t HAL_I3C_CTRL_EnableHotJoinAllowed(hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_CTRL_DisableHotJoinAllowed(hal_i3c_handle_t *hi3c);

hal_status_t HAL_I3C_CTRL_EnableHighKeeperSDA(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_CTRL_DisableHighKeeperSDA(const hal_i3c_handle_t *hi3c);

HAL I3C device configuration type definition

HAL1

HAL2 

typedef struct
 {
   uint8_t         DeviceIndex;

   uint8_t         TargetDynamicAddr;

   FunctionalState IBIAck;
   FunctionalState IBIPayload;
   FunctionalState CtrlRoleReqAck;
   FunctionalState CtrlStopTransfer;
 } I3C_DeviceConfTypeDef;

typedef struct
 {
   uint8_t device_index;

   uint8_t tgt_dynamic_addr;

   hal_i3c_ctrl_ibi_ack_status_t        ibi_ack;
   hal_i3c_ctrl_ibi_payload_status_t    ibi_payload;
   hal_i3c_ctrl_role_ack_status_t       ctrl_role_req_ack;
   hal_i3c_ctrl_stop_transfer_status_t  ctrl_stop_transfer;
 } hal_i3c_ctrl_device_config_t;

HAL I3C ENTDAA payload type definition

HAL1

HAL2 

typedef struct
 {
   I3C_BCRTypeDef   BCR;
   uint32_t         DCR;
   I3C_PIDTypeDef   PID;
 } I3C_ENTDAAPayloadTypeDef;

typedef struct
{
  hal_i3c_bcr_t  bcr;
  uint32_t       dcr;
  hal_i3c_pid_t  pid;
} hal_i3c_entdaa_payload_t;

HAL I3C FIFO configuration type definition

HAL1

HAL2 

typedef struct
 {
   uint32_t RxFifoThreshold;
   uint32_t TxFifoThreshold;
   uint32_t ControlFifo;


   uint32_t StatusFifo;

 } I3C_FifoConfTypeDef;

typedef struct
 {
   hal_i3c_rx_fifo_threshold_t  rx_fifo_threshold;
   hal_i3c_tx_fifo_threshold_t  tx_fifo_threshold;
   hal_i3c_ctrl_fifo_t          ctrl_fifo;
 } hal_i3c_ctrl_fifo_config_t;

 hal_status_t HAL_I3C_CTRL_EnableStatusFifo(hal_i3c_handle_t *hi3c);
 hal_status_t HAL_I3C_CTRL_DisableStatusFifo(hal_i3c_handle_t *hi3c);

HAL I3C handle type definition

HAL1

HAL2 

I3C_HandleTypeDef

hal_i3c_handle_t

Related concepts:

HAL I3C initialization type definition

HAL1

HAL2 

typedef struct
 {
   LL_I3C_CtrlBusConfTypeDef CtrlBusCharacteristic;



   LL_I3C_TgtBusConfTypeDef  TgtBusCharacteristic;


 } I3C_InitTypeDef;

The structure I3C_InitTypeDef and its member structures LL_I3C_CtrlBusConfTypeDef and LL_I3C_TgtBusConfTypeDef have been removed. Timing configuration is now calculated using the utility functions STM32_UTILS_I3C_CTRL_ComputeTiming and STM32_UTILS_I3C_TGT_ComputeTiming, by filling in the equivalent structure stm32_utils_i3c_ctrl_timing_config_t.

HAL I3C PID type definition

HAL1

HAL2 

typedef struct
{
  uint16_t  MIPIMID;
  uint8_t   IDTSEL;
  uint16_t  PartID;
  uint8_t   MIPIID;

} I3C_PIDTypeDef;

typedef struct
{
  uint16_t  mipi_manuf_id;
  uint8_t   id_type_sel;
  uint16_t  part_id;
  uint8_t   mipi_id;
} hal_i3c_pid_t;

HAL I3C TGT configuration type definition

The I3C_TgtConfTypeDef structure has been split into four separate structures in HAL2, with additional configuration options now managed by dedicated functions.

HAL1

HAL2 

typedef struct
{
  uint8_t Identifier;

  uint8_t MIPIIdentifier;

  FunctionalState CtrlRoleRequest;

  FunctionalState HotJoinRequest;

  FunctionalState IBIRequest;

  FunctionalState IBIPayload;

  uint32_t IBIPayloadSize;

  uint16_t MaxReadDataSize;

  uint16_t MaxWriteDataSize;

  FunctionalState CtrlCapability;

  FunctionalState GroupAddrCapability;

  uint32_t DataTurnAroundDuration;

  uint8_t MaxReadTurnAround;

  uint32_t MaxDataSpeed;

  FunctionalState MaxSpeedLimitation;

  uint32_t HandOffActivityState;

  FunctionalState HandOffDelay;

  FunctionalState PendingReadMDB;


} I3C_TgtConfTypeDef;

typedef struct
{
  uint8_t identifier;

  uint8_t mipi_identifier;

  hal_i3c_ctrl_role_status_t             ctrl_role;
  hal_i3c_ibi_payload_status_t           ibi_payload;
  hal_i3c_max_speed_limitation_status_t  max_data_speed_limitation;
} hal_i3c_tgt_config_payload_entdaa_t;

typedef struct
{
  hal_i3c_tgt_payload_size_t         ibi_payload_size_byte;
  hal_i3c_tgt_read_mdb_status_t      pending_read_mdb;

} hal_i3c_tgt_ibi_config_t;

typedef struct
{
  hal_i3c_getmxds_format_t          getmxds_format;
  hal_i3c_handoff_activity_state_t  ctrl_handoff_activity;
  hal_i3c_turnaround_time_tsco_t    data_turnaround_duration;
  uint8_t max_read_turnaround;
} hal_i3c_tgt_getmxds_config_t;

HAL_I3C_TGT_SetConfigMaxDataSize(const hal_i3c_handle_t *hi3c, uint32_t max_read_data_size_byte,
                                     uint32_t max_write_data_size_byte);
hal_status_t HAL_I3C_TGT_EnableCtrlRoleRequest(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_TGT_DisableCtrlRoleRequest(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_TGT_EnableHotJoinRequest(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_TGT_DisableHotJoinRequest(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_TGT_SetConfigIBI(const hal_i3c_handle_t *hi3c, const hal_i3c_tgt_ibi_config_t *p_config);
hal_status_t HAL_I3C_TGT_EnableIBI(const hal_i3c_handle_t *hi3c);
hal_status_t HAL_I3C_TGT_DisableIBI(const hal_i3c_handle_t *hi3c);

HAL I3C callback type definition

HAL1

HAL2

pI3C_CallbackTypeDef

hal_i3c_cb_t

pI3C_NotifyCallbackTypeDef

hal_i3c_notify_cb_t

pI3C_TgtHotJoinCallbackTypeDef

hal_i3c_tgt_hot_join_cb_t

pI3C_TgtReqDynamicAddrCallbackTypeDef

hal_i3c_req_dyn_addr_cb_t

Related concept: Replaced TypeDef suffix with _t in type names